하네스 엔지니어링 시도중...

원래는 Superpowers를 쓰고 있었는데, 최근에는 여기에 compound engineering 비슷한 흐름을 더해서 테스트해보고 있다.

다만 아직 제대로 테스트가 끝난 건 아니다. 생각보다 토큰을 많이 먹는다. 특히 프론트랑 백엔드를 0부터 전부 만들려고 하면 토큰이 너무 많이 든다.

그래서 최근에는 토큰 절약 스킬들을 살펴보고 있다. 시도해볼려고하는 것은 context-mode와 rtk 정도 생각하고 있다.

Superpowers에서 괜찮았던 것

그래도 추천하고 싶은 건 Superpowers에 있는 Brainstorming 스킬이다.

내가 프롬프트를 대충 던져도, 부족한 부분이나 더 필요한 정보를 계속 물어봐준다. 바로 답하기 애매한 부분은 선택지도 준다. 그래서 내가 뭘 만들고 싶은지 아직 흐릿할 때 꽤 유용했다.

비슷하게 grill-me 같은 스킬도 괜찮다. 이것도 내가 애매하게 말한 걸 기준으로 계속 질문하면서 빠진 정보를 채워주는 느낌이다.

물론 내가 뭘 해야 하는지, 어떤 파일을 수정해야 하는지 정확히 알고 있다면 이런 스킬을 쓸 필요는 별로 없다. 그럴 땐 그냥 파일을 지정하고 바로 프롬프트를 입력해서 실행하거나 좀 큰 규모면 plan mode로 검토하고 실행하는 것이 나았다.

반대로 내가 뭘 해야 할지 애매하거나, 요구사항이 아직 정리되지 않았거나, 어떤 파일을 봐야 할지 모를 때는 Brainstorming이나 grill-me 같은 걸 먼저 쓰는 게 나았다.

grill-me SKILL.md 내용

• 사실 grill-me라는 스킬 내부에는 이런 프롬프트 하나 뿐이다.
• 토큰을 아끼고싶고 코드베이스가 중요하지 않을 때(어떤 상황인지 인지하고 있을 때)
  • 미리 일반 GPT와 아래 프롬프트로 사용해서 내용을 구성하고 진행하는 것도 나쁘지 않은 방법인 것 같다.

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore the codebase instead.

컨텍스트 관리

출력 토큰이 비싼 것도 문제지만, 입력 토큰도 컨텍스트가 커질수록 꽤 부담이 된다.

그리고 컨텍스트가 쌓이면 에이전트가 점점 멍청해지는 느낌이 있다. 이미 끝난 내용을 계속 고려하거나, 예전 요구사항과 지금 요구사항을 섞거나, 필요 없는 파일까지 다시 보려고 한다.

내 체감은 대충 이렇다.

70% 근처: 슬슬 압축을 고려
80% 이상: 웬만하면 compact
태스크가 끝나거나 주제가 바뀜: clear 또는 새 세션

나는 작업 도중이어도 80% 정도 넘으면 거의 무조건 압축시키는 편이다. 70% 정도에서도 압축할 때가 있다. 체감상 70%에 가까워질수록 점점 느려지고 답변 품질도 떨어지는 느낌이 있었다.

다만 작업 중간에 compact를 하면 그때도 멍청해지는 타이밍이 있다. compact가 내가 원하는 내용을 전부 잘 보존해주는 건 아니기 때문이다. 대화 흐름에서 중심 문장만 가져와서 요약하는 느낌이라, 내가 중요하게 생각한 세부사항이 빠질 수 있다.

Claude에서는 /compact 내가 남기길 원하는 부분 이런 식으로 어느 정도 유도할 수 있었던 것 같은데, Codex에는 그게 없어서 아쉬웠다.

그래서 요즘은 중요한 내용은 대화에만 남기지 않고 /docs/ 아래에 md 파일로 남기는 편이다.

문서로 남기는 방식

지금 생각하는 구조는 대충 이렇다.

/AGENTS.md
  에이전트가 지켜야 할 규칙, 테스트 명령, 금지사항

/docs/PRD.md
  기능 요구사항

/docs/PLAN.md
  구현 계획, 작업 순서

/docs/DESIGN.md
  디자인 규칙

/docs/DECISIONS.md
  왜 이렇게 결정했는지 기록

/docs/HANDOFF.md
  compact나 clear 전에 남기는 인수인계 문서

특히 HANDOFF.md가 꽤 중요하다.

compact 하기 전에 이런 식으로 시킨다.

compact하기 전에 /docs/HANDOFF.md에 작업내용 업데이트해줘.

포함할 것:
- 현재 목표
- 완료한 작업
- 아직 안 한 작업
- 수정한 파일
- 다음에 바로 할 일
- 조심해야 할 제약사항

그다음 새 세션이나 compact 이후에는 이렇게 시작한다.

/docs/HANDOFF.md, /docs/PRD.md, /docs/PLAN.md를 먼저 읽고
이어서 작업해줘.

이렇게 하면 컨텍스트가 날아가도 그냥 compact하거 작업하는 것보다 나은 것 같다..

태스크를 작게 나누는 게 중요함

결국 제일 좋은 건 compact가 필요한 상황까지 가기 전에 작업을 작게 나누는 것 같다.

예를 들어 이렇게 한 번에 시키는 건 별로였다.

이 프로젝트 전체를 완성해줘.
프론트, 백엔드, DB, 인증, 배포까지 다 해줘.

이러면 토큰도 많이 들고, 중간에 방향이 틀어졌을 때 되돌리기도 어렵다.

차라리 이렇게 나누는 게 낫다.

1. 요구사항 정리
2. 데이터 모델 설계
3. API 설계
4. 인증 구현
5. 메인 페이지 UI 구현
6. 테스트 추가
7. 리팩터링

그리고 각 단계가 끝날 때마다 문서를 업데이트하고, 필요하면 새 세션으로 넘어가는 방식이 더 안정적인 것 같다.

DESIGN.md

이것도 최근에 보는 중이라 100% 좋다고 말하기는 어렵다. 그래도 꽤 흥미로웠다.

간단히 말하면 DESIGN.md는 에이전트가 일관성 있는 디자인을 만들 수 있게 해주는 디자인 지침서 같은 느낌이다. 색상, 타이포그래피, 버튼, 카드, 레이아웃 같은 기준을 미리 적어두는 식이다.

요즘 DESIGN.md를 제공하는 사이트들도 좀 보인다.

getdesign.md
  여러 사이트의 DESIGN.md 예시를 볼 수 있음

designmd.me
  기존 웹사이트 URL을 넣어서 DESIGN.md를 뽑아볼 수 있음

하나 정도 테스트해봤는데 나쁘지 않았다.

작성한 DESIGN.md를 바로 에이전트에 넣기 전에 GPT에 넣고 메인 페이지만 생성해보는 식으로 미리 확인해봤는데, 빠르게 감을 보기에는 괜찮았다.

Stitch에도 넣어봤는데 결과가 꽤 일관성 있게 나왔다. 이게 DESIGN.md 때문인지 Stitch 성능이 좋아서인지는 아직 잘 모르겠다. 그래도 export할 때 DESIGN.md를 같이 주는 점은 좋았다. 당분간은 Stitch를 좀 더 활용해볼 생각이다.

DESIGN.md에 넣으면 좋을 것 같은 것

아직 정답은 모르겠지만, 대충 이런 내용은 들어가면 좋은 것 같다.

- 이 서비스가 어떤 느낌이어야 하는지
- 색상 규칙
- 폰트 크기와 굵기
- 여백 규칙
- 버튼 / 카드 / input 같은 컴포넌트 규칙
- 모바일에서 어떻게 보여야 하는지
- 접근성 관련 규칙
- 하지 말아야 할 디자인

특히 하지 말아야 할 디자인을 적는 게 생각보다 중요해 보인다.

에이전트는 냅두면 흔한 SaaS 랜딩페이지처럼 만들거나, 보라색-파란색 그라데이션 같은 걸 자주 쓰는 느낌이 있다. 그래서 이런 식으로 금지 규칙을 적어두면 좋다.

Do not:
- generic purple-blue SaaS gradient 쓰지 말 것
- 필요 이상으로 큰 hero section 만들지 말 것
- 정해진 버튼 스타일 외에 새 버튼 스타일 만들지 말 것
- 한 화면에서 font weight를 너무 많이 쓰지 말 것
- 중요한 텍스트를 너무 연한 회색으로 쓰지 말 것

지금 기준으로 제일 괜찮은 흐름

아이디어가 애매함 or 프롬프트를 보강하고 싶음
→ Brainstorming / grill-me

요구사항이 어느 정도 정리됨
→ PRD.md 작성

구현 전에
→ PLAN.md 작성

UI가 필요함
→ DESIGN.md 작성 또는 Stitch 활용

구현 단계(변경점이 확실한 경우)
→ 파일 범위 지정하고 diff 중심으로 요청

작업 도중 압축을 시도할 때
→ HANDOFF.md 업데이트

컨텍스트가 70~80% 이상 쌓임
→ compact 또는 새 세션

태스크가 끝남
→ clear

정리하면, 프롬프트를 잘 쓰는 것도 중요하지만 그보다 더 중요한 건 에이전트가 다시 읽고 이어갈 수 있는 문서를 프로젝트 안에 남기는 것 같다.

대화창에 기억을 맡기기보다는, 기억해야 할 내용을 레포에 남기는 쪽이 더 안정적이었다.